一般元规则

编码

使用 UTF-8（无 BOM）。

确保你的编辑器将没有字节顺序标记的 UTF-8 用作字符编码。

注释

用注释解释代码的覆盖范围、目的和作用以及使用和选择各解决方案的原因。

你可以选择使用 JSDoc，即编写代码注释的文件生成器和标准，对你的 JavaScript 功能进行记录，其优点包括为你的注释提供技术参照和能够针对文件生成网页的命令行 jsdoc 工具。 JSDoc 会为你提供记录代码的多种注释，但我们只推荐你使用以下种类：

  • @constructor：用于记录类别，即用新关键词调用的函数。
  • @description：用于描述你的函数，该标签还可以使你在需要时添加 HTML 标记。
  • @param：用于描述函数参数的名称、类别和说明。
  • @returns：记录函数返回值的类型和说明。

该实例说明了如何记录类构造器（注意注释区开头使用的 /**，这个非常重要）：

  1. /**
  2. * @description 简要描述这本书
  3. * @constructor
  4. * @param {string} title - 书的标题
  5. * @param {string} author - 书的作者
  6. */
  8. function Book(title, author) {
  9.     ...
  10. }

以下函数含有能返回值的参数，注意，这里的参数作用一目了然，因此并未对其进行说明。

  1. /**
  2. * @description 添加两个数字
  3. * @param {number} a
  4. * @param {number} b
  5. * @returns {number} 数字 a 与 b 的和
  6. */
  8. function sum(a, b) {
  9.     return a + b;
  10. }

你也可以使用更多你想要编写的注释。